package com.dxg.msns.user.service;

import com.dxg.msns.common.pojo.PageResult;
import com.dxg.msns.common.pojo.UserHistory;
import com.dxg.msns.common.pojo.UserHistoryDetailVO;

import java.util.List;

/**
 * 用户历史记录Service接口
 */
public interface UserHistoryService {

    /**
     * 添加或更新用户播放历史记录
     * 如果该用户已经播放过该音乐，则更新播放时间
     * 如果没有播放过，则新增记录
     * 
     * @param userHistory 用户历史记录对象
     * @return 操作结果消息
     */
    String addOrUpdateUserHistory(UserHistory userHistory);

    /**
     * 分页查询用户历史记录
     * 
     * @param userId 用户ID
     * @param page   页码
     * @param rows   每页大小
     * @return 分页结果
     */
    PageResult<UserHistory> queryUserHistoryByPage(String userId, Integer page, Integer rows);

    /**
     * 查询用户所有历史记录（不分页）
     * 
     * @param userId 用户ID
     * @return 历史记录列表
     */
    List<UserHistory> queryUserHistoryAll(String userId);

    /**
     * 根据用户ID和音乐ID查询特定历史记录
     * 
     * @param userId  用户ID
     * @param musicId 音乐ID
     * @return 历史记录
     */
    UserHistory queryUserHistoryByUserIdAndMusicId(String userId, String musicId);

    /**
     * 统计用户历史记录总数
     * 
     * @param userId 用户ID
     * @return 历史记录总数
     */
    Long countUserHistory(String userId);

    /**
     * 清空用户所有历史记录
     * 
     * @param userId 用户ID
     * @return 操作结果消息
     */
    String clearUserHistory(String userId);

    /**
     * 删除特定的历史记录
     * 
     * @param userId  用户ID
     * @param musicId 音乐ID
     * @return 操作结果消息
     */
    String deleteUserHistory(String userId, String musicId);

    /**
     * 分页查询用户历史记录详情（包含音乐信息和收藏状态）
     * 
     * @param userId 用户ID
     * @param page   页码
     * @param rows   每页大小
     * @return 分页结果
     */
    PageResult<UserHistoryDetailVO> queryUserHistoryDetailsWithPage(String userId, Integer page, Integer rows);

    /**
     * 查询用户所有历史记录详情（包含音乐信息和收藏状态）
     * 
     * @param userId 用户ID
     * @return 历史记录详情列表
     */
    List<UserHistoryDetailVO> queryUserHistoryDetailsAll(String userId);
}